.TH std::atomic_exchange,std::atomic_exchange_explicit 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::atomic_exchange,std::atomic_exchange_explicit \- std::atomic_exchange,std::atomic_exchange_explicit

.SH Synopsis
   Defined in header <atomic>
   template< class T >

   T atomic_exchange( std::atomic<T>* obj,                            \fB(1)\fP \fI(since C++11)\fP

                      typename std::atomic<T>::value_type desired )
   noexcept;
   template< class T >

   T atomic_exchange( volatile std::atomic<T>* obj,                   \fB(2)\fP \fI(since C++11)\fP

                      typename std::atomic<T>::value_type desired )
   noexcept;
   template< class T >

   T atomic_exchange_explicit( std::atomic<T>* obj,
                               typename std::atomic<T>::value_type    \fB(3)\fP \fI(since C++11)\fP
   desired,

                               std::memory_order order ) noexcept;
   template< class T >

   T atomic_exchange_explicit( volatile std::atomic<T>* obj,
                               typename std::atomic<T>::value_type    \fB(4)\fP \fI(since C++11)\fP
   desired,

                               std::memory_order order ) noexcept;

   1,2) Atomically replaces the value pointed to by obj with the value of desired and
   returns the value obj held previously, as if by obj->exchange(desired).
   3,4) Atomically replaces the value pointed to by obj with the value of desired and
   returns the value obj held previously, as if by obj->exchange(desired, order).

.SH Parameters

   obj     - pointer to the atomic object to modify
   desired - the value to store in the atomic object
   order   - the memory synchronization ordering

.SH Return value

   The value held previously by the atomic object pointed to by obj.

.SH Example

   A spinlock mutex can be implemented in userspace using an atomic exchange operation,
   similar to std::atomic_flag_test_and_set:


// Run this code

 #include <atomic>
 #include <iostream>
 #include <thread>
 #include <vector>

 std::atomic<bool> lock(false); // holds true when locked
                                // holds false when unlocked

 int new_line{1}; // the access is synchronized via atomic lock variable

 void f(int n)
 {
     for (int cnt = 0; cnt < 100; ++cnt)
     {
         while (std::atomic_exchange_explicit(&lock, true, std::memory_order_acquire))
             ; // spin until acquired
         std::cout << n << (new_line++ % 80 ? "" : "\\n");
         std::atomic_store_explicit(&lock, false, std::memory_order_release);
     }
 }

 int main()
 {
     std::vector<std::thread> v;
     for (int n = 0; n < 8; ++n)
         v.emplace_back(f, n);
     for (auto& t : v)
         t.join();
 }

.SH Possible output:

 02222222222222222222222002222222222222222222222222222222222222222222222222222222
 22222222200022222222202222211111111111110000011111111100000000000000110001111111
 00011111000001111110000011111100000111000000001111111111111110000010000001001111
 11011111111011111011000000000000111100000000000001111000011133333333333333333333
 33333333333333333333333333333333333333333333333333333333333333333333333333333333
 44444444444444444444444444444444444444444444444444444444444444444444444444444444
 44444444444444444444555555555555555555555555555555555555555555555555555555555555
 55555555555555555555555555555555555555556666666666666666666666666666666666666666
 66666666666666666666666666666666666666666666666666666666666677777777777777777777
 77777777777777777777777777777777777777777777777777777777777777777777777777777777

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR    Applied to         Behavior as published         Correct behavior
   P0558R1 C++11      exact type match was required because T is only deduced
                      T was deduced from multiple arguments from obj

.SH See also

                                           atomically replaces the value of the atomic
   exchange                                object and obtains the value held previously
                                           \fI(public member function of std::atomic<T>)\fP

   atomic_compare_exchange_weak
   atomic_compare_exchange_weak_explicit   atomically compares the value of the atomic
   atomic_compare_exchange_strong          object with non-atomic argument and performs
   atomic_compare_exchange_strong_explicit atomic exchange if equal or atomic load if
   \fI(C++11)\fP                                 not
   \fI(C++11)\fP                                 \fI(function template)\fP
   \fI(C++11)\fP
   \fI(C++11)\fP

   std::atomic_exchange(std::shared_ptr)          specializes atomic operations for
   std::atomic_exchange_explicit(std::shared_ptr) std::shared_ptr
   (deprecated in C++20)                          \fI(function template)\fP
   (removed in C++26)
   C documentation for
   atomic_exchange,
   atomic_exchange_explicit
